home *** CD-ROM | disk | FTP | other *** search
/ Aminet 28 / Aminet 28 (1998)(GTI - Schatztruhe)[!][Dec 1998].iso / Aminet / dev / c / dice-3.16.lha / doc / stdio.doc < prev    next >
Text File  |  1993-07-06  |  57KB  |  2,454 lines
  1.  
  2.     STDIO.DOC (c)Copyright 1990, Matthew Dillon, All Rights Reserved
  3.  
  4. TABLE OF CONTENTS
  5.  
  6. c.lib/stdio/clearerr
  7. c.lib/stdio/fclose
  8. c.lib/stdio/fdopen
  9. c.lib/stdio/feof
  10. c.lib/stdio/ferror
  11. c.lib/stdio/fflush
  12. c.lib/stdio/fgetc
  13. c.lib/stdio/fgetpos
  14. c.lib/stdio/fgets
  15. c.lib/stdio/filbuf
  16. c.lib/stdio/fileno
  17. c.lib/stdio/fopen
  18. c.lib/stdio/fprintf
  19. c.lib/stdio/fputc
  20. c.lib/stdio/fputs
  21. c.lib/stdio/fread
  22. c.lib/stdio/freopen
  23. c.lib/stdio/fscanf
  24. c.lib/stdio/fseek
  25. c.lib/stdio/fsetpos
  26. c.lib/stdio/ftell
  27. c.lib/stdio/fwrite
  28. c.lib/stdio/getc
  29. c.lib/stdio/getchar
  30. c.lib/stdio/gets
  31. c.lib/stdio/perror
  32. c.lib/stdio/pfmt
  33. c.lib/stdio/printf
  34. c.lib/stdio/putc
  35. c.lib/stdio/putchar
  36. c.lib/stdio/puts
  37. c.lib/stdio/remove
  38. c.lib/stdio/rename
  39. c.lib/stdio/rewind
  40. c.lib/stdio/scanf
  41. c.lib/stdio/setbuf
  42. c.lib/stdio/setvbuf
  43. c.lib/stdio/sprintf
  44. c.lib/stdio/sscanf
  45. c.lib/stdio/stdin
  46. c.lib/stdio/stdout
  47. c.lib/stdio/stderr
  48. c.lib/stdio/tmpfile
  49. c.lib/stdio/tmpnam
  50. c.lib/stdio/ungetc
  51. c.lib/stdio/vfprintf
  52. c.lib/stdio/vprintf
  53. c.lib/stdio/vsprintf
  54.  
  55.  
  56. stdio/file_pointer                        stdio/file_pointer
  57.  
  58.     A file pointer is the basis for STDIO, a standard file buffering
  59.     package across all versions of C.
  60.  
  61.     The specific Amiga implementation uses file descriptors (see
  62.     the file_descriptor manual page) as its interface to the
  63.     filesystem.
  64.  
  65.     Remember that a stdio file pointer is NOT a file descriptor nor
  66.     an AmigaDOS file handle.  You may call only stdio routines (fopen,
  67.     fclose, fread, fwrite, etc...) with file pointers.
  68.  
  69.     Some C implementations flush stdout whenever stdin is read.  DICE
  70.     does not do this.
  71.  
  72.  
  73.  
  74. stdio/clearerr                        stdio/clearerr
  75.  
  76.    NAME
  77.     clearerr - clear error associated with a file pointer
  78.  
  79.    SYNOPSIS
  80.     #include <stdio.h>
  81.  
  82.     void clearerr(fp);              (MACRO)
  83.     FILE *fp;
  84.  
  85.    FUNCTION
  86.     The clearerr() macro clears both the EOF flag and the ERROR
  87.     flag associated with a file pointer.  When an ERROR occurs on
  88.     a file pointer further fread, fwrite, and some other calls will
  89.     not work (i.e. fail) until the ERROR indicator is cleared.
  90.  
  91.    NOTE
  92.     refer to the file_pointer manual page for general information
  93.  
  94.    INPUTS
  95.     FILE *fp;    file pointer to clear the error on.
  96.  
  97.    RESULTS
  98.     none,    the error and EOF indicators are cleared
  99.  
  100.    SEE ALSO
  101.     feof, ferror, rewind, fseek
  102.  
  103.  
  104. stdio/fclose                        stdio/fclose
  105.  
  106.    NAME
  107.     fclose - close a file pointer
  108.  
  109.    SYNOPSIS
  110.     #include <stdio.h>
  111.  
  112.     int error = fclose(fp);
  113.     FILE *fp;
  114.  
  115.    FUNCTION
  116.     fclose flushes any data remaining in the file pointer's
  117.     output buffer to the file and then closes the file.  The
  118.     file pointer is no longer valid.
  119.  
  120.     fclose returns any error condition that occured while flushing
  121.     the buffered data to the file.    The file is still closed even
  122.     if an error occurs.
  123.  
  124.    NOTE
  125.     You can fclose(stdin), fclose(stdout), and fclose(stderr) as
  126.     you wish to save space and/or detach your process from the
  127.     console (i.e. allow the console window to be closed).
  128.  
  129.    WARNING
  130.     If you fclose stdin, stdout, and stderr with the intension of
  131.     removing all references to the console window there is still
  132.     one more thing you have to do, and that is put a NULL in
  133.     your processes pr_ConsoleTask field.  Otherwise, while the
  134.     console window will be able to close, your process will still
  135.     have a reference to the now non existant window if it attempts
  136.     to spawn or Execute() other processes.
  137.  
  138.     refer to the file_pointer manual page for general information
  139.  
  140.    INPUTS
  141.     FILE *fp;    file pointer
  142.  
  143.    RESULTS
  144.     int error;    error on fclose, or 0 if none
  145.  
  146.    SEE ALSO
  147.     fopen, fread, fwrite, fgets, fputs
  148.  
  149.  
  150. stdio/fdopen                        stdio/fdopen
  151.  
  152.    NAME
  153.     fdopen - associate a file pointer with an already open file
  154.          descriptor
  155.  
  156.    SYNOPSIS
  157.     #include <stdio.h>
  158.  
  159.     FILE *fp = fdopen(fd, modes);
  160.     int fd;
  161.     char *modes;
  162.  
  163.    FUNCTION
  164.     fdopen associates an already open file descriptor with a file
  165.     pointer.  Note that fclose()ing the file pointer will also
  166.     close() the file descriptor.
  167.  
  168.     Refer to the fopen manual page for a description of available
  169.     modes.    Note that when you use fdopen the file will not be
  170.     truncated and if you specify mode 'a' for append, the file
  171.     descriptor MUST have been open()'d with the O_APPEND flag.
  172.  
  173.     That is, the mode string should be similar to the open flags
  174.     that were used to open the file descriptor.
  175.  
  176.    NOTE
  177.     refer to the file_pointer manual page for general information
  178.  
  179.    INPUTS
  180.     int fd;     file descriptor to associated with a new file pointer
  181.     char *modes;    modes string, such as "r+".
  182.  
  183.    RESULTS
  184.     FILE *fp;    new file pointer or NULL if an error occured
  185.  
  186.    SEE ALSO
  187.     fopen, fread, fwrite, fgets, fputs
  188.  
  189.  
  190. stdio/feof                        stdio/feof
  191.  
  192.    NAME
  193.     feof   - return EOF condition for file pointer
  194.  
  195.    SYNOPSIS
  196.     #include <stdio.h>
  197.  
  198.     int r = feof(fp);                   (MACRO)
  199.     FILE *fp;
  200.  
  201.    FUNCTION
  202.     feof returns the EOF status of a file pointer.    The status is
  203.     not changed by this macro.  0 is returned if no EOF condition
  204.     exists, non-zero if an EOF condition exists (NOT necessarily
  205.     1 or -1, just non-zero).
  206.  
  207.     use clearerr() to clear the EOF condition.  Also, fseek() and
  208.     rewind() also clear an EOF condition.
  209.  
  210.    NOTE
  211.     refer to the file_pointer manual page for general information
  212.  
  213.    INPUTS
  214.     FILE *fp;    file pointer
  215.  
  216.    RESULTS
  217.     int r;        0 if no EOF condition exists, != 0 if an EOF
  218.             condition exists (not necessarily 1 or -1).
  219.  
  220.    SEE ALSO
  221.     fopen, fclose, fread, fwrite, fgets, fputs
  222.  
  223.  
  224. stdio/ferror                        stdio/ferror
  225.  
  226.    NAME
  227.     ferror - return ERROR condition for file pointer
  228.  
  229.    SYNOPSIS
  230.     #include <stdio.h>
  231.  
  232.     int r = ferror(fp);                 (MACRO)
  233.     FILE *fp;
  234.  
  235.    FUNCTION
  236.     ferror returns the ERROR status of a file pointer.  The status is
  237.     not changed by this macro.  0 is returned if no ERROR condition
  238.     exists, non-zero if an ERROR condition exists (NOT necessarily 1 or
  239.     -1, just non-zero).
  240.  
  241.    NOTE
  242.     refer to the file_pointer manual page for general information
  243.  
  244.    INPUTS
  245.     FILE *fp;    file pointer
  246.  
  247.    RESULTS
  248.     int r;        0 if no ERROR condition exists, != 0 if an ERROR
  249.             condition exists (not necessarily 1 or -1).
  250.  
  251.    SEE ALSO
  252.     fopen, fclose, fread, fwrite, fgets, fputs
  253.  
  254.  
  255. stdio/fflush                        stdio/fflush
  256.  
  257.    NAME
  258.     fflush - flush buffers to file
  259.  
  260.    SYNOPSIS
  261.     #include <stdio.h>
  262.  
  263.     int error = fflush(fp);
  264.     FILE *fp;
  265.  
  266.    FUNCTION
  267.     fflush writes out any buffered data out to the file descriptor
  268.     associated with the file pointer.
  269.  
  270.     Normally a file is either unbuffered, line buffered, or fully
  271.     buffered.  fflush is useful in the later two cases as is shown
  272.     by the example.
  273.  
  274.     fflush will return -1 if a write error occured, 0 if no error
  275.     occured.
  276.  
  277.    NOTE
  278.     refer to the file_pointer manual page for general information
  279.  
  280.    EXAMPLE
  281.     /*
  282.      *  Since text to stdout is normally line buffered, if we do not
  283.      *  write out a newline '\n' then the line is still buffered in
  284.      *  memory and we have to fflush() to write it out.
  285.      */
  286.  
  287.     #include <stdio.h>
  288.  
  289.     main()
  290.     {
  291.         char buf[256];
  292.  
  293.         printf("Enter a number -");
  294.         fflush(stdout);
  295.         gets(buf);
  296.         printf("Munch Munch...");
  297.         fflush(stdout);
  298.         sleep(1);
  299.         puts("Thanks!");
  300.     }
  301.  
  302.    INPUTS
  303.     FILE *fp;    file pointer
  304.  
  305.    RESULTS
  306.     int error;    0 if no error, -1 on error.
  307.  
  308.    SEE ALSO
  309.     fopen, fclose, fread, fwrite, fgets, fputs
  310.  
  311.  
  312. stdio/fgetc                        stdio/fgetc
  313. stdio/getc                        stdio/getc
  314.  
  315.    NAME
  316.     fgetc - get a single character from a file pointer
  317.     getc  - get a single character from a file pointer (MACRO)
  318.  
  319.    SYNOPSIS
  320.     #include <stdio.h>
  321.  
  322.     int c = fgetc(fp);
  323.     int c = getc(fp);                   (MACRO)
  324.     FILE *fp;
  325.  
  326.    FUNCTION
  327.     [f]getc() reads a single character from a file pointer.  The value
  328.     returned is actually an int because EOF (-1) must be differentiated
  329.     from a 255.
  330.  
  331.     [f]getc() returns an integer 0-255 or EOF (-1) if an end of file
  332.     occurs.
  333.  
  334.    NOTE
  335.     refer to the file_pointer manual page for general information
  336.  
  337.    EXAMPLE
  338.     /*
  339.      *  copy stdin to stdout using getc/putc.  Normally one uses
  340.      *  fread/fwrite, but I'll save that for the fread manual page.
  341.      *
  342.      *  note that I output the initial message to stderr so it does
  343.      *  not get stuck into stdout in case the user has redirected
  344.      *  stdout.
  345.      */
  346.  
  347.     #include <stdio.h>
  348.  
  349.     main()
  350.     {
  351.         int c;
  352.  
  353.         fputs("Type a couple of lines, then ^\ (EOF)\n", stderr);
  354.         while ((c = getc(stdin)) != E